IRIX Base Documentation 1998 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat1 / pixie.z / pixie

Wrap

Text File | 1998-10-30 | 18KB | 397 lines

PPPPIIIIXXXXIIIIEEEE((((1111)))) PPPPIIIIXXXXIIIIEEEE((((1111)))) NNNNAAAAMMMMEEEE pixie - add profiling code to an executable file SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ppppiiiixxxxiiiieeee file [ options ] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN _p_i_x_i_e is an object instrumentation tool that can be used to measure code execution frequency in a program for performance analysis. _p_i_x_i_e reads an executable program, partitions it into basic blocks, and writes an equivalent program containing additional code that counts the execution of each basic block. (A basic block is a region of the program that can be entered only at the beginning and exited only at the end). Other options allow producing an uninstrumented copy of the executable, with map and graph sections added, and producing an instrumented executable for just counting function calls (arcs). _p_i_x_i_e is normally invoked from the SpeedShop _s_s_r_u_n(1) command; when it is so invoked, the SpeedShop runtime will be inserted into the program, and, when the program is run, it will generate a SpeedShop experiment file with the appropriate count data. Data will be generated if the process exits normally, or received a fatal signal, unless the user has installed his or her own handler for that signal. If the process invokes any of the various _d_l_o_p_e_n() calls, the DSO requested will be automatically instrumented, and the instrumented version added to the process. _p_r_o_f(1) can analyze these files and produce a listing of profiling data. See its man pages for more details. _e_l_f_d_u_m_p(1) can be used to dump out the contents of the various sections added to an executable by _p_i_x_i_e. _p_i_x_i_e(1) adds its runtime _D_S_O(5) to the liblist of the executable. The normal rules _r_l_d(1) uses for LD_LIBRARY_PATH, _RLD_ROOT, and their abi variants apply to locating the _p_i_x_i_e runtime dso _l_i_b_p_i_x_r_t._s_o. DDDDIIIIRRRREEEECCCCTTTT IIIINNNNVVVVOOOOCCCCAAAATTTTIIIIOOOONNNN OOOOFFFF PPPPIIIIXXXXIIIIEEEE _p_i_x_i_e may also be directly invoked by a user, in which case the SpeedShop runtime is not inserted. When the instrumented program is run, it will generate a file containing the basic block counts. The pixified executable will creat a counts file in the event of fatal signals as long as the executable does not override the signal handlers set up by the _p_i_x_i_e(1) runtime. The name of the output .Counts file is that of the original program with any leading directory names removed and ".Counts" appended. If the program during runtime executes calls to _s_p_r_o_c(_2) , _s_p_r_o_c_s_p_c(_2) or _f_o_r_k(_2) then multiple ".Counts" files will be generated, one for each process in the share group. In this case, each ".Counts" file will additionally have the process id appended to the name. If the process invokes any of the various _d_l_o_p_e_n() calls, the DSO requested will NOT be PPPPaaaaggggeeee 1111 PPPPIIIIXXXXIIIIEEEE((((1111)))) PPPPIIIIXXXXIIIIEEEE((((1111)))) automatically instrumented; it is the user's responsibility to pre- instrument all such DSOs. When instrumenting DSO's it is necessary to use one of the following switches: ----ddddssssoooo, ----ddddssssoooo33332222, ----ddddssssoooo66664444, depending on whether the DSO is o32, n32, or n64 respectively. _p_r_o_f(1) can analyze these .Counts files and produce a listing of profiling data. If the ".Counts" file has a process id number appended to it, you will need to give prof the full name including the suffix. See the prof man pages for more details. OOOOPPPPTTTTIIIIOOOONNNNSSSS _p_i_x_i_e is normally invoked by the _s_s_r_u_n(1) command, and not directly invoked by a user. It recognizes the following arguments: ----ccccooooppppyyyy Produce a copy of the target with function list (map) and arc list (graph) sections, but no instrumentation. ----ffffccccnnnnccccoooouuuunnnnttttssss Produce an instrumented executable that counts function calls and arc calls, but not basic-block- or branch-counts. ----aaaaddddddddlllliiiibbbbssss _l_i_b_1._s_o:_l_i_b_2._s_o:..._l_i_b_N._s_o Specify one or more DSOs that should be add to the library list of the executable (if they are not already explicitly there). Default: no libraries are added. ----ppppiiiixxxxiiiieeee____ffffiiiilllleeee <_n_a_m_e> Specify the name of the pixiefied executable. Default: append ".pixie" (or an explicit suffix, as set by ----ssssuuuuffffffffiiiixxxx) to the original name. ----ccccoooouuuunnnnttttssss____ffffiiiilllleeee <_n_a_m_e> Specify the name to be used for the output .Counts file. Default: append ".Counts" to the original program name. ----ssssuuuuffffffffiiiixxxx <._s_u_f_f_i_x> Specify the suffix to be appended to the pixified executable and DSO. Default: For an a.out, append ".pixie" (although _s_s_r_u_n(1) always explicitly sets the suffix). For DSOs, the default suffix depends on the build architecture of the DSO; for o32 it is ".pix32", for n32, it is ".pixn32", and for n64 it is ".pix64". ----ddddssssoooo Treat executable as a o32 DSO. Performs a search of standard o32 library directories (and LD_LIBRARY_PATH), and causes a "._p_i_x_3_2" extension to be used. ----ddddssssoooo33332222 Treat executable as a n32 DSO. Performs a search of standard n32 library directories (and PPPPaaaaggggeeee 2222 PPPPIIIIXXXXIIIIEEEE((((1111)))) PPPPIIIIXXXXIIIIEEEE((((1111)))) LD_LIBRARYN32_PATH), and causes a "._p_i_x_n_3_2" extension to be used. ----ddddssssoooo66664444 Treat executable as a n64 DSO. Performs a search of standard n64 library directories (and LD_LIBRARY64_PATH), and causes a "._p_i_x_6_4" extension to be used. ----ddddiiiirrrreeeeccccttttoooorrrryyyy _d_i_r_e_c_t_o_r_y__n_a_m_e Specify a directory for writing the output file(s). Default: Current directory, "./". ----[[[[nnnnoooo]]]]aaaauuuuttttooooppppiiiixxxxiiiieeee [Prevents] or permits a recursive instrumenting with pixie of all dynamic shared libraries used by the input file during runtime. _p_i_x_i_e keeps the timestamp and checksum from the original executable. Before automatically instrumenting a shared library _p_i_x_i_e will check any <lib>.pixie that it finds matching the <lib> it is to instrument and sees if the fields match. If so they will not be re- instrumented. This option is not useful if the input file is non- shared. All DSO's used by the executable must to be instrumented in order for it to work correctly. Default: ----aaaauuuuttttooooppppiiiixxxxiiiieeee for an executable; ----nnnnooooaaaauuuuttttooooppppiiiixxxxiiiieeee for a DSO. ----[[[[nnnnoooo]]]]vvvveeeerrrrbbbboooosssseeee [Prevents] or permits messages summarizing the binary-to-binary translation process. Default: ----nnnnoooovvvveeeerrrrbbbboooosssseeee ----[[[[nnnnoooo]]]]lllloooonnnnggggbbbbrrrraaaannnncccchhhh When _p_i_x_i_e instruments the user program, some transformations can push a branch offset beyond its legal range and _p_i_x_i_e will generate warnings about branch offsets being out of range. The -longbranch option will cause _p_i_x_i_e to transform these instructions into jumps. Default: ----nnnnoooolllloooonnnnggggbbbbrrrraaaannnncccchhhh ----[[[[nnnnoooo]]]]ppppiiiiddddssss This option tells _p_i_x_i_e to append the process id number on the end of the ``.Counts'' name. This is useful if you want to run the program instrumented with _p_i_x_i_e through a variety of tests before generating the statistics with _p_r_o_f. This option is only needed for the main program. It will be transferred automatically to the instrumented DSO's during runtime. The -nopids options will always be overridden by a process that issues a _f_o_r_k(2) or _s_p_r_o_c(2) system call. Default: ----nnnnooooppppiiiiddddssss The following options are currently supported for compatibility reasons, but are considered obsolescent, and will eventually be removed. If you feel they are necessary for your work, please contact us. PPPPaaaaggggeeee 3333 PPPPIIIIXXXXIIIIEEEE((((1111)))) PPPPIIIIXXXXIIIIEEEE((((1111)))) ----[[[[nnnnoooo]]]]lllliiiibbbblllliiiisssstttt [Prevents] or permits printing the names and paths of dynamic shared libraries used by the input file during runtime. This uses the same default search path strategy used by _r_l_d and _p_r_o_f. This list is useful for building a dependency list for makefiles and shell scripts. The name of the file is that of the original program with any leading directory names removed and ".liblist" appended. While pixie can not detect and pre-instrument any DSOs that the program dynamically opens, the SpeedShop runtime does detect them, and will cause them to be instrumented before proceeding with the _d_l_o_p_e_n. Default: ----nnnnoooolllliiiibbbblllliiiisssstttt ----[[[[nnnnoooo]]]]lllliiiibbbblllliiiissssttttoooonnnnllllyyyy [Prevents] or permits printing the names and paths of dynamic shared libraries used by the input file during runtime. This is the same as -_l_i_b_l_i_s_t except that in this case no other operations are performed. Default: ----nnnnoooolllliiiibbbblllliiiissssttttoooonnnnllllyyyy ----[[[[nnnnoooo]]]]bbbbrrrraaaannnncccchhhhccccoooouuuunnnnttttssss [Prevents] or permits insertion of extra counters to track whether each branch instruction is taken or not taken. When this option is used, _p_r_o_f understands the new information automatically and prints more statistics. The information produced: branch to branch taken branch to branch untaken untaken conditional branches taken conditional branches taken conditional branches with bnop untaken conditional branches with bnop direction-predicted conditional branches with bnop non-sequential fetches taken branches per conditional branch forward taken branches per conditional branch forward untaken branches per conditional branch backward taken branches per conditional branch backward untaken branches per conditional branch Default: ----bbbbrrrraaaannnncccchhhhccccoooouuuunnnnttttssss. ----[[[[nnnnoooo]]]]ttttaaaabbbblllleeee [Disable] or enable dumping an ascii map of translations made by _p_i_x_i_e into the file <myprog>.table where <myprog> is the name of the original object. Default: ----nnnnoooottttaaaabbbblllleeee ----[[[[nnnnoooo]]]]ccccaaaallllllll____ccccoooouuuunnnnttttssss [Disable] or enable collecting function invocation counts. This is used in conjunction with _p_r_o_f -_g_p_r_o_f. Default: ----ccccaaaallllllll____ccccoooouuuunnnnttttssss PPPPaaaaggggeeee 4444 PPPPIIIIXXXXIIIIEEEE((((1111)))) PPPPIIIIXXXXIIIIEEEE((((1111)))) ----tttthhhhrrrreeeeeeeewwwwaaaayyyy _h_e_x _n_u_m_b_e_r Tell _p_i_x_i_e not to transform code around threeway transfers. Such code lies in libgl.so and exists only on machines which have VGX,GTX and Reality Engine graphics boards. The number for the Reality Engine is 0x3000 and the number for VGX and GTX is 0x6000. Most applications are not affected by this, so it is recommended this option not be used unless the graphics are obviously behaving differently from the non-instrumented version. The erroneous behavior most common is for the graphics to be completely black. Since _p_i_x_i_e currently uses a heuristic to find the threeway patterns it can be fooled into thinking it has found a threeway transfer when in fact it has not. Because of this, _p_i_x_i_e does not pass the -_t_h_r_e_e_w_a_y flag automatically to the shared object and the user must run _p_i_x_i_e separately on libgl.so when using -_t_h_r_e_e_w_a_y. Default: nnnnoooo tttthhhhrrrreeeeeeeewwwwaaaayyyy ssssuuuuppppppppoooorrrrtttt ----mmmmiiiippppssss1111 Use the MIPS1 instruction set (R2000, R3000) for output executable. This option is only useful for translating a mips2 executable into a mips1 executable. If the executable is mips3 or greater it will have no affect. Default: the architecture of the input executable will be maintained. SSSSEEEEEEEE AAAALLLLSSSSOOOO prof(1), ssrun(1), speedshop(1) NNNNOOOOTTTTEEEESSSS Some programs, e.g., _u_n_c_o_m_p_r_e_s_s and _v_i, will treat their arguments differently when the name of the program is different. If you are running the program manually, you may need to rename _m_y_p_r_o_g._p_i_x_i_e to _m_y_p_r_o_g for example. If you are running the program with _s_s_r_u_n, the program will think it was invoked with the original name. When _p_i_x_i_e reports the size of the old and new code, the numbers are accurate in that the new code size reported is the size of the code _p_i_x_i_e will actually execute. However, the new code size does not count read- only data (including a copy of the original text and another data block the same size as the original text) put into the text section. _s_i_z_e(1) on the _p_i_x_i_e output reports a much larger text size than _p_i_x_i_e, since _s_i_z_e counts everything in the text segment as text. Code instrumented by _p_i_x_i_e is substantially larger than the original code. Conditional branches that used to fit in the 16-bit branch displacement field are specially handled and normally do not generate a _p_i_x_i_e error. In certain cases in which they cannot be handled, a warning may be generated. _p_i_x_i_e(1) currently cannot handle stripped programs. _p_i_x_i_e will give a fatal error if it is invoked on a stripped executable. PPPPaaaaggggeeee 5555 PPPPIIIIXXXXIIIIEEEE((((1111)))) PPPPIIIIXXXXIIIIEEEE((((1111)))) _p_i_x_i_e(1) sets the PIXIE_INIT bit of the processor-specific flags in the ELF .dynamic section. This guarantees the pixie-inserted initialization code of a dynamic shared libraries is executed before any other init code. See _l_d(1). PPPPaaaaggggeeee 6666